The New Template Generator - Background

Introduction

With WebsydianExpress v3.5 a new template generator has been created in order to generate templates to be used by the page generators.

The main focus areas of the new Template Generator are:

• Template generated to be close to the final version
• Possible customization of the generator to meet the demands for your web projects
• Change management - allow changes to the final template and still be able to re-run the template generation
• Support for creating advanced templates to meet the requirements of RIA based web application based on the Sencha ExtJS javascript framework

Background

The two main parts that makes the template generator are:

1. A function named _CreateTemplates that needs to be scoped to the page generator by inheriting from the abstract function named TemplateGenerator/_CreateTemplates that is available from the library WSYAPI. This function is required to be generated and build prior to executing it directly in the Plex IDE Generate and Build window. It can be generated as a Java or Windows C++ function depending on the variant of the WSYTMPL library model.
2. The actual template generation component which is supplied as a runtime component with Websydian and is called by the _CreateTemplates function from within the Plex IDE. 

The following describes the architecture of the template generator, a short introduction to the different parts of the template generator and how the template generation is executed.

The steps to complete and performed by the template generator

1. It all starts in your model where you are to generate and build the _CreateTemplates function scoped to the page generator. When this is done you can run the _CreateTemplate function from within the Plex IDE generate and build window.
2. When the _CreateTemplates function is executed it will start by creating an XML file holding all important information about the page generator in question and its event handlers, fields, options etc.
   
   The next step for the _CreateTemplates function is to call the Websydian Template Generator which is supplied with Websydian as a runtime component; parsing in the name and location of the XML file to the Template Generator. 

3. The Template Generator uses information from the XML file together with the meta templates in order to create the required final templates for your page generator,

4. The template generator drops the created templates into the output folder for created templates. This folder could be the html folder of WebsydianExpress but is configurable when you setup the template generator. Depending on the meta templates a number of files will be created with different file suffix. E.g. a .JS file and a .HTML file.

Meta templates

The meta templates can be viewed upon as the recipes that make up the creation of your final templates. As an addition the meta templates also hold information on how to obtain the ingredients for your final templates. The ingredients being information from the XML file a long with the markup within the meta template it self.

The Template Generator starts by reading the XML file in order to locate the meta templates folder to be used for creating the template for the page generator in question. The starting point for the template generator is the meta templates named MAIN.xxx. For each MAIN.xxx meta template the template generator will create the corresponding final template replacing MAIN with the implementation name of the page generator. E.g. if we have MAIN.js and MAIN.htm in the meta template folder and a page generator with the implementation name WSMYPAGE the template generator will create the final templates named WSMYPAGE.js and WSMYPAGE.htm.

For you to understand the methodology of the meta templates and the template generation we have put together a small sample. In this sample we will be creating a final template that will simply be a text file with information from the XML file. The template generator always starts its creation by locating the MAIN.xxx meta template so if we have a MAIN.txt meta template it could look something like this.

At the top you see the content of MAIN.TXT and at the bottom you see the Page element of the XML file. It is important to know that each meta template will reference a specific element in the XML file.

In the case of the MAIN meta template the current element in the XML file is the Page element.

If you ran the template generator against this meta template you would get a final template named WACUSTUPD.txt with the following content:

Besides the text that we added to the MAIN.txt meta template we also added some script markers, in this case the /(%GETVALUE-@xxxxxxx). This script marker is one of many but most likely the most widely used in the meta templates. The /(%GETVALUE-@xxx) script marker instructs the meta template to retrieve the value of an attribute within the current element of the XML file, in this case the Page element.

Where the MAIN meta template can get information from the Page element of the XML file there are other meta templates that can be used to get information about other elements of the XML file.

Lets extend the example above to include information about all output fields of the page generator, that is the fields added to the variable WsyDetails.

We start by adding a new line to the MAIN.txt meta template.

Then we add another meta template named DETAILFIELDS.txt. The DETAILFIELDS meta template is the other type of meta templates you will see, this is a grid meta template. It is constructed to iterate through all occurrences of a repeating element in the XML document like the Field element.

The output fields of this page generator are:
<!--/(GRID)-->
Plex scoped name.: /(%GETVALUE-@plex_Scopedname)
    Name.........: /(%GETVALUE-@plex_name)
    Impl. name...: /(%GETVALUE-@plex_impl)
    Control type.: /(%GETVALUE-wsycontroltype)
    Data type....: /(%GETVALUE-@wsydatatype)
    Label........: /(%GETVALUE-@plex_label)
<!--/(GRID)-->
No more output fields defined

When running the template generation now the output would look something like this (depending on the number of fields on the page generator)

The first thing we did was add the script marker /(%INCLUDE-DETAILFIELDS) to the MAIN.txt meta template this instructs the MAIN.txt meta template to call the meta template named DETAILFIELDS and include any output from this into the final template.

Then we created the DETAILFIELDS.txt meta template. The DETAILFIELDS.txt meta template is a grid meta template and will iterate through all Field elements of the XML document that are scoped to the Region element with attribute plex_name with value of WsyDetails. Between the <!--/(GRID)--> markers each Field within the XML definition file will become current element which allows us to use the /(%GETVALUE-@xxxxx) in order to retrieve the attributes of each field.

The meta templates can vary in complexity so if you need to see some more samples then have a look in the metatemplates folder supplied in the TemplateGenerator folder of your Websydian installation. A hint is always start with the MAIN.xxx files and then work your way down.